How do Top Sites (Shortcuts) work?
Top sites are the sites that appear in the first section of the homepage as tiles. They are mostly used as shortcuts for users to quickly access their favorite sites, or show their most visited sites.
There are currently a total of five different tile types in Top Sites:
- Google tile
- Default suggested tiles
- Pinned tiles
- Sponsored tiles
- Frecency tiles Each tile type has precedence over other types, depending on the number of tiles we can show on a device.
There's different telemetry collected for tiles. Example with this Looker dashboard.
-
Googlerefer in this case to the Google tile -
History-basedrefers to the Frecency tiles -
Sponsoredrefers to the Sponsored tiles -
Suggestedrefers to the Default suggested tiles -
User-Addedrefers to the pinned tiles More context is given on all tiles below in subsequent sections of this page.
The layout of the top sites section can change depending on the device it's shown in. There's two major factor affecting the number of tiles that will show:
- The user preference on the number of rows, which can be set from the Settings menu
- The device's screen width. Each tile space has a fixed width, and so we calculate the number of tiles that can fit inside a certain screen width to know how many tiles can show. When the layout of the homepage is setup, and we know how many tiles we can show, we can then go down the path of figuring out which tiles have precedence over which tiles.
Normally, on iPhone portrait mode there will be 4 tiles per row. The number of row by default is of 2, so most iPhone users will see 8 tiles. If they rotate to portrait, there should be around 8 tiles per row, which means 16 tiles total if the default number of row is set.
On iPad the number of tiles per row can vary by a significant amount, since the user can have different device size which will amount to a different number of tiles per row. The user can also go in multitasking mode which could potentially resemble the number of tiles an iPhone user can get.
The google tile is always the first tile to show in the section. It shows up as a pinned tile. It will be added if there's enough space to show. It will not be added if there's a greater number of pinned tiles than the number of tiles we can show. Once added, it will continue to be shown until the user decides to remove it (by long pressing on the tile a menu appears which enables the user to do so). The GoogleTopSiteManager manages this tile. Google tile has precedence over sponsored tiles and frecency tiles.
A user can add pinned tiles in their top sites by visiting a website and selecting "Add to Shortcuts" from the menu. The user can also remove a pinned tile by long pressing the tile and selecting the related action for that. Pinned tiles have precedence over sponsored tiles and frecency tiles.*
Pinned tiles data comes from the TopSitesProvider. Any tiles that is pinned by the user gets saved inside the SQLHistory database. Any time a user removes a tile, it respectively gets removed from that database.
*: Pinned tiles are supposed to have precedence over sponsored tiles, but in the current implementation, pinned tiles only gain precedence over sponsored tiles when the amount of pinned tiles exceeds the maxTopSites (56 pinned tiles). At this point where
maxTopSitesis exceeded, sponsored tiles will no longer show. Essentially, it is unlikely for a user, that pinned sites will ever precede sponsored sites.
Up-to-date information on sponsored tiles in this wiki page.
When first installing the application, we have default tiles called SuggestedSite that are set depending on the user's locale. The default suggested tiles are tiles that are bundled in the application. This ensures there's always tiles that are shown in the top sites, even if the users don't have any history-based tiles or pinned tiles.
Once a user start navigating, the rest of the tiles spaces will get populated with every visit to a new website. Each time a user visit a website, the visit gets recorded in RustPlaces. When we fetch the frecency data from RustPlaces, we use the following function func getTopFrecentSiteInfos(limit: Int, thresholdOption: FrecencyThresholdOption) -> Deferred<Maybe<[Site]>> which can be found here.
For more information on what this query returns, please see the Frecency Algorithm documentation
To help visualize the tiles precedence, here's a diagram.
🟡 Note: This section is only applicable post homepage redesign 🟡
There are two different layout styles for favicons, depending on whether the image contains transparency in its background:
Favicons without transparency: These are rendered edge-to-edge with no background.
Favicons with transparency: These icons are inset slightly within their container to reveal a predefined background behind them. This ensures transparent regions are visible and visually balanced against the rest of the UI.
 |
 |
|---|---|
| Favicon without transparency | Favicon with transparency |